home *** CD-ROM | disk | FTP | other *** search
/ Aminet 41 / Aminet 41 (2001)(Schatztruhe)[!][Feb 2001].iso / Aminet / util / sys / Ver.lha / Version / VersionString.doc < prev    next >
Text File  |  2000-12-20  |  4KB  |  103 lines
  1.  
  2. - version.doc ---------------------------------------------------------
  3.  
  4. Version Command
  5. ===============
  6.  
  7. There has been some confusion about what the format of version strings
  8. are. The exact format is detailled in the Amiga User Interface Style Guide
  9. on page 110.  The format is:
  10.  
  11.  $VER: <name> <version>.<revision> (dd.mm.yy)
  12.  
  13. example: $VER: FooBar 1.1 (23.5.92)
  14.  
  15. The string starts with $VER: followed by a space, followed by <name>.
  16. <name> is the name of the program.  <name> can NOT contain any spaces.
  17. You can use underscores to achieve a similar effect. 
  18.  
  19. After <name> comes a single space, followed by <version>.  <version> is
  20. the major version number for the program.  There should be no leading
  21. zeros. 
  22.  
  23. After  <version>  comes  a  dot, followed by <revision>.  <revision> is the
  24. minor version number for the program.  There should be no leading zeros.
  25.  
  26. Following the revision number comes a space, and then the date.  The date
  27. is specified in numeric form only, with no leading zeros on any of the
  28. components.  First comes the day of the month, then the month, then the
  29. two digits year.  In the future, a four digit year format will also be
  30. supported, but not yet.
  31.  
  32. After <date> may be comes a single space, optional followed by a little
  33. comment. since OS 39, this part of text will be printed by using a new line.
  34.  
  35. The versionstring self terminates by a linefeed or NULL and should not be
  36. larger than 80 chars.
  37.  
  38. Embedding a version string in the exact format described above will let
  39. the C/Version command find the version string.  In the future, there will
  40. be a system call to enable applications, and other system tools, to obtain
  41. the version information from files easily. 
  42.  
  43. ROM Tags.  The version command not only looks for the $VER: version
  44. strings, it also search executable files for standard ROM tags.  ROM tags
  45. only contain a version number, they have no revision or date fields.  The
  46. recommended approach is to store a pointer to a version string in the
  47. RT_IDSTRING field of the ROM tag. This string should be in the same format
  48. as the normal version string, except without the "$VER: " prefix. 
  49.  
  50. An executable file containing a ROM tag with a properly initialized
  51. RT_IDSTRING field does not need any other version information in it, such
  52. as a separate $VER-style string. 
  53.  
  54. Leading Zeros.  Leading zeros are not supported as part of the version and
  55. revision numbers. So "2.04" is not a valid version/revision pair as far as
  56. the version command is concerned.  The reason this is so is because of the
  57. VERSION and REVISION command-line options of the Version command.  These
  58. allow the version and revision of a file to be checked by a script such
  59. as:
  60.  
  61.    Version asl.library VERSION 38 REVISION 4
  62.  
  63. The above command will return 0 if asl.library is greater or equal to
  64. 38.4, and 5 if it is not.  Specifying:
  65.  
  66.    Version asl.library VERSION 38 REVISION 04
  67.  
  68. Does the same thing.  This means that from the standpoint of the Version
  69. command, 2.04 is the same as 2.4, and thus 2.04 evaluates as being greater
  70. than 2.1, which is not the desired effect.  So, the version and revision
  71. numbers must not be treated as a floating-point number, but as two
  72. separate and distinct integers. 
  73.  
  74. This brings up the concept of user versions and internal versions.  V37 is
  75. known to the public as Release 2.04, and V39 is known as 3.0.  All the
  76. version strings in the system software use version strings starting with
  77. V39.  The recommended approach is as follows:
  78.  
  79.    o Assign your products user-space numbers of the form 2.04 and the like. 
  80.  
  81.    o Assign the various components of your distribution the same version
  82. numbers as for your product.  For example, "2". 
  83.  
  84.    o Assign each individual components of your distribution their own
  85. unique, monotonically increasing revision numbers.  These numbers have
  86. nothing to do with the user- space number of your product as a whole. 
  87.  
  88. An example is in order.  Assume a word processor called
  89. "SliceAndDiceWord", which is at version 4.03.  All the files composing the
  90. distribution would have a version number of "4", and a file-specific
  91. revision number:
  92.  
  93.    Package number : SliceAndDiceWord 4.03
  94.    Main executable: SADW 4.1423
  95.    Support library: SADW.library 4.4129
  96.    README file    : SADW.README 4.6
  97.  
  98. When SliceAndDiceWord 5.0 comes out, all the version numbers of the files
  99. included with the distribution get bumped to 5, and the revision numbers
  100. start at 0 again. 
  101.  
  102. -eof version.doc ------------------------------------------------------
  103.